This is a draft info browser for FWEB.  Although this is not complete, one can find the principal pieces of information that are presented in the reference guide.

--- INTRODUCTION to FWEB ---

FWEB is an extension of Knuth's WEB system that handles C, C++, Fortran, Ratfor, and TeX.  It features the ability to handle multiple languages within a single run, a built-in C-like macro preprocessor, and a style file that enables one to change the behavior of many of FWEB's features.

FWEB is a modification of an early version of CWEB that was graciously supplied by Silvio Levy.

--- WEB CONCEPTS; FWEB FEATURES ---

The best general reference to the concepts of WEB and literate programming is D. E. Knuth, ``Literate Programming'' (Center for the Study of Language and Information, Leland Standard Junior University, 1992).

FWEB introduces the concept of a current language *Note Languages:: so more than one compiler language can be processed in a single WEB run.

FWEB contains a built-in Ratfor (RATional FORtran) translator.  *Note Ratfor::

FWEB also has a built-in C-like macro preprocessor, which should be especially useful for Fortran and Ratfor. *Note Macros:: *Note Preprocessing::

Please see the user manual fwebman.tex for a full discussion of all features of FWEB.  A concise summary of syntax and other features can be found in guide.tex, which consists of several appendices from the full manual.

--- FILES ---

FWEB works with a variety of files.  File names have the form [path]/root[.ext], where the brackets denote optional.  Here the slash is called the PREFIX_END_CHAR.  Since this character differs for various operating systems, it can be changed in custom.h. *Note Customization:: The character that initiates the file-name extension (normally a period) can be changed with the -E command-line option. *Note -E::

FWEB's input files:

.fweb --- Initialization file; always in the home directory.

fweb.sty --- Style file; in current directory unless changed by environment variable FWEB_STYLE_DIR.  The basic name can be changed by the -z option. *Note -z::

name.web --- Source code.

name.ch --- Change file.

name.hweb --- Code included into web file with @i.  *Note @i:: Include files are searched for in the path set by the environment variable FWEB_*INCLUDES and/or the -I option.  *Note -I:: If that path is empty, then the current directory is searched.

name.hch --- Change file for include file.

Automatic completion of input file names is turned on by the `-e' command-line option.  *Note -e:: When in effect, input file names that include no period (have no extension) are completed automatically according to the contents of the following style-file entries:

Type of file    Style-file entry        Default

WEB file           ext.web                .web

Change file        ext.ch                 .ch

Include file       ext.hweb               .hweb

Change file

for include file  ext.hch                .hch

More than one extension may be specified, as a space-delimited list---e.g., "web wb"; the first one that matches is used.

FWEB's output files:

name.tex --- Woven output to be processed with TeX or LaTeX.

CONTENTS.tex --- Temporary file that accumulates table-of-contents information.

INDEX.tex --- Temporary file that stores indexing information.

MODULES.tex --- Temporary files that stores module list.

name.ext --- Compilable output file.

The names of the three temporary files can be changed with style-file options.  *Note Style:: Commonly, one may put into the style file fweb.sty commands such as

index.tex "#.ndx"

modules.tex "#.mds"

contents.tex "#.cdts"

The '#' is replaced by the root name of the web file.

Please see the manual for a complete discussion of change files. *Note @x:: *Note @y:: *Note @z::

The command-line syntax is

     ftangle-|
             | webfile[.web] [changefile[.ch]] [-option...]
     fweave--|

File names are anything that doesn't begin with a '-'.  Options begin with a '-'.  File names and options can be intermixed.  The first file name encountered is the web file (source file); the second, if it exists, is the change file.

An option consisting of a lone hyphen stands for the special file name ``stdin'', which means ``read from the standard input.''

The web file is shown as required since one is normally processing a source.  However, a few of the information options *Note Info options:: will work even in the absence of a web file.

--- WEB COMMANDS ---

All WEB commands begin with the character `@'.

WEB command `@@':  The character '@'.

`@@' inserts the single character '@'.

Don't forget to double the at even inside strings.  For example,

-------------------------------------------------------------------------------
puts("'@@' is represented by `@@@@'");
-------------------------------------------------------------------------------

WEB command `@|':  Literal vertical bar, or optional line break.

In TeX mode, `@|' inserts a vertical bar.

In code mode, `@|' inserts an optional line break in an expression.

WEB command `@ ':  Begin minor module.

`@ ' begins a new minor (unstarred) module.  For example,

-------------------------------------------------------------------------------

     @ This is an example of a minor module.  (No entry is made in the table
     of contents.)
     @a
     main()
     {}

-------------------------------------------------------------------------------

WEB commands `@*', `@*n':  Begin major module.

`@*' begins a new major (starred) module (of level 0).  The command must be followed by the name of the module (entry in the table of contents), followed by a period.

If `@*' is followed by a digit n, it begins a new major module of level n. For example,

-------------------------------------------------------------------------------

     @* MAIN PROGRAM.  This begins a major module (of level 0).
     @a
     main()
     {}

     @*1 Input routines.  Now follow some subroutines.
     @a
     get_input()
     {}

-------------------------------------------------------------------------------

WEB command `@<':  Begin module name.

`@<' begins a module name, which has the form

@< TeX text @>

(Module names inside WEB macro definitions begin with `@#', not `@<'.)

WEB command `@>':  End module name.

`@>' ends a module name, of the form @< TeX text @>.

WEB command `@A':  Begin code part of unnamed module.

`@A' begins the code part of an unnamed module.  For example,

-------------------------------------------------------------------------------

      In an unnamed module, the code part begins with `@a'.
     @a
     main()
     {}

-------------------------------------------------------------------------------

WEB command `@a':  Begin code part of unnamed module, and mark.

`@a begins the code part of an unnamed module (just as does `@A'), and in addition marks the next unreserved identifier it finds as defined in this module.  Precisely,

`@a' == `@A@['

WEB command `@b':  Insert a breakpoint command.

For example,

-------------------------------------------------------------------------------

     @
     @a
     main()
     {
     @b
     }

-------------------------------------------------------------------------------

WEB command `@c':  Set language to C.

*Note Languages:: *Note C::

WEB command `@c++:  Set language to C++.

*Note Languages:: *Note C++::

WEB command `@D':  Define outer macro.

`@D' defines an outer macro.  *Note Outer macros:: For example,

-------------------------------------------------------------------------------
@D A 1
-------------------------------------------------------------------------------

WEB command `@d':  Define outer macro, and mark.

`@d' defines an outer macro (just as `@D' does), and also marks the next identifiers as defined here.  It is equivalent to

`@d' == `@D@['

WEB command `@e':  Pseudo-expression.

`@e' is an invisible expression.  *Note Pseudo-operators::

WEB command `@f':  Format identifier or module name.

For example,

------------------------------------------------------------------------------
@f mytype int
-------------------------------------------------------------------------------

says to treat the variable |mytype| just as |int| is treated (e.g., as a reserved word in C or C++).

WEB command `@i':  Include file (unconditional).

If one says

-------------------------------------------------------------------------------
@i test.hweb
-------------------------------------------------------------------------------

the file test.hweb is inserted at the present point of the web file.  By default, the current directory is searched.  Files can be included from other directories by means of the FWEB_INCLUDES environment variable and/or the `-I' command-line option. *Note Environment variables:: *Note -I_::

WEB command `@I':  Include file (conditional).

This commands behaves like @i if the command-line option `-i' is not used.  If it is used, then the contents of the included file is not printed in the woven output. *Note -i:: *Note -i!::

WEB command `@L':  Set language.

`@Ll' sets the language to l, where l is one of {c,c++,n,n9,r,r9,x}. *Note Languages::

WEB command `@l':  Specify limbo text.

Limbo text is material that FWEAVE should output before the start of the first module.  For example,

-------------------------------------------------------------------------------
@l "\\def\\A{abc}"
-------------------------------------------------------------------------------

Note that '\\' stands for a backslash.  In general, characters must be escaped just as in C.

WEB command `@M':  Define WEB macro.

Please see the manual for a detailed discussion of WEB macros.

WEB command `@m':  Define WEB macro, and mark.

WEB command `@n':  Set language to Fortran--77.

*Note Languages:: *Note Fortran::

WEB command `@n9':  Set language to Fortran--90.

*Note Languages:: *Note Fortran::

WEB command `@O':  Open output file (global scope).

WEB command `@o':  Open output file (local scope).

WEB command `@r':  Set language to Ratfor--77.

*Note Languages:: *Note Ratfor::

WEB command `@r9':  Set language to Ratfor--90.

*Note Languages:: *Note Ratfor::

WEB command `@u':  Undefine outer macro.

WEB command `@v':  Overload operator.

Please see the manual for a detailed discussion of overloading operators.

WEB command `@W':  Overload identifier.

Please see the manual.

WEB command `@x':  Terminate ignorable material.

Please see the discussion of the @z command. *Note @z::

WEB command `@z':  Begin ignorable material.

FWEB files may begin with the construction

-------------------------------------------------------------------------------

     @z
     .
     .
     @x

-------------------------------------------------------------------------------

Material between the @z and @x is pure commentary and is ignored by both processors.

WEB command @':  Convert character to ASCII.

The constuction @'A' translates to the octal representation of the character 'A' in the ASCII character set.

WEB command `@"':  Convert string to ASCII.

The construction @"abc" converts the enclosed string to its ASCII representation.

WEB command `@[':  Mark as defined.

WEB command `@/*':  Begin long verbatim comment.

WEB command `@//':  Begin short verbatim comment.

WEB command `@%':  Ignorable comment.

If any line in a web source code contains the command `@%', all remaining material on that line is ignored by the input driver and never processed at all.

WEB command `@?':  Begin compiler directive.

The remainder of the line is processed as compiler directive.  Optional material may be inserted automatically at the beginning of the tangled output line by means of the style-file option cdir_start.  *Note cdir_start::

WEB command `@(':  Begin meta-comment.

Material between @( and @) is treated as verbatim comments; for example,

-------------------------------------------------------------------------------

     @(
     Comment 1
     Comment 2
     @)

-------------------------------------------------------------------------------

For more information, see the style-file parameters beginning with ``meta''. *Note meta.bottom:: *Note meta.prefix:: *Note meta.TeX.begin:: *Note meta.TeX.end:: *Note meta.top::

WEB command `@)':  End meta-comment.

WEB command `@{':  Suppress insertion of breakpoint command.

This is for detailed debugging of FWEB codes; please see the manual.

WEB command `@_':  Force index entry to be underlined.

WEB command `@-':  Delete index entry.

WEB command `@^':  Make index entry (Roman type).

To insert one's own index entry in Roman type, say  ``@^My entry@>''.

WEB command `@.':  Make index entry (typewriter type).

To insert one's own index entry in typewriter type, say  ``@^My entry@>''.

WEB command `@9':  Make index entry (\9 format).

The construction ``@9text@>'' is used to create an index entry in a format defined by the user.  It is associated with the macro \9, which the user must define according to the format

\def\9#1{...}

WEB command `@t':  Put control text into a TeX \hbox.

WEB command `@=':  Pass control text verbatim to the output.

WEB command `@,':  Insert a thin space.

WEB command `@/':  Force a line break.

For example,

-------------------------------------------------------------------------------

     int@/
       i,@/
       j,@/
       k;

-------------------------------------------------------------------------------

WEB command `@|':  Literal vertical bar, or optional line break.

In TeX mode, `@|' inserts a vertical bar.  Here's a LaTeX example:

-------------------------------------------------------------------------------

     \begin{verbatim}
       The constructions @|x@| and |x| are very different.
     \end{verbatim}

-------------------------------------------------------------------------------

In code mode, `@|' inserts an optional line break in an expression.

WEB command `@#':  Blank line.

`@#' forces a line break with some extra vertical white space.  Note that blank lines in the source are significant, so this command should seldom be necessary.

if `@#' is immediately followed by a letter, it is assumed that a preprocessor command is beginning.  *Note Preprocessing::

WEB command `@+':  Cancel line break.

For example,

-------------------------------------------------------------------------------
printf("Working..."); @+ fflush(stdout);
-------------------------------------------------------------------------------

WEB command `@&':  Join items.

`@&' joins the items to either side with no spaces or line breaks inbetween.

WEB command `@e':  Pseudo-expression.

`@e' is an invisible expression.  *Note Pseudo-operators::

WEB command `@;':  Pseudo-semicolon.

`@;' is an invisible semicolon.  *Note Pseudo-operators::

WEB command `@:':  Pseudo-colon.

`@:' is an invisible colon.  *Note Pseudo-operators:: It can be helpful in formatting certain C constructions correctly.  For example,

-------------------------------------------------------------------------------

     @<Cases@>=
     case 1:
     case 2:
     case 3@:

-------------------------------------------------------------------------------

--- COMMAND-LINE OPTIONS ---

Command-line options may be put into the initialization file .fweb. In that file, options beginning with a plus sign are processed before the command-line options.  Otherwise, they are processed after the command-line options.

To negate a command-line option, use an extra hyphen.  For example, `--v' means ``Don't make all comments verbatim.''  This kind of construction is useful if an option such as  `-v' is turned on in the .fweb initialization file and you wish to turn it off for just one run.

Command-line option `-1':  Turn on brief debugging mode (FWEAVE).

Displays irreducible scraps.

Command-line option `-2':  Turn on verbose debugging mode (FWEAVE).

Displays detailed reductions of the scraps.

Command-line option `-a':  Turn on ASCII translations.

Command-line option `-b':  Number blocks.

Number do and if blocks in woven Fortran and Ratfor output.

Command-line option `-c':  Set global language to C.

*Note Languages:: *Note C::

Command-line option `-c++':  Set global language to C++.

*Note Languages:: *Note C++::

Command-line option `-D':  Display reserved words.

This option displays the list of reserved words for the language currently in force.  Thus, to see the reserved words for Ratfor--90, say

ftangle -Lr9 -D

(For this option one must set the language on the command line, because the -D option is processed before the limbo section of the web file is read.)

If you say `-Dabc', you will get just the reserved words that begin with "abc".

Command-line option `-d':  Convert do...enddo.

Command-line option `-E':  Change the delimiter of a file-name extension.

The standard delimiter for file-name extensions is a period, as in ``test.web''.  To change this character to a comma, for example, say

``-E,''

Command-line option `-e':  Turn on automatic file-name completion.

When the `-e' option is in effect, FWEB attempts to be helpful in figuring out what file name you intend.  For any input file name that has no extension (no embedded period), FWEB completes the name by adding the extension contained in the style-file parameter listed in the following table:

Type of file    Style-file entry        Default

WEB file           ext.web                .web
Change file        ext.ch                 .ch
Include file       ext.hweb               .hweb
Change file
for include file  ext.hch                .hch

More than one extension may be specified, as a space-delimited list---e.g., "web wb"; the first one that matches is used.

Command-line option `-f':  Turn off module references for identifiers.

By default, FWEAVE gives certain entities such as function names a section-number subscript to indicate where that function was defined. The `-f' command turns off the subscripting operation.

Command-line option `-h':  Get help.

This just prints a message saying where further help is available.

Command-line option `-I':  Append to search list for include files.

The fundamental search list for include files is defined by the environment variable FWEB_INCLUDES, which is a colon-delimited list such as

setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff

The `-I' option appends to this list.

Command-line option `-i':  Don't print @I include files.

If a web file is included via `@I', *Note @I_:: for example

-------------------------------------------------------------------------------
@I formats.hweb
-------------------------------------------------------------------------------

then the `-i' option means to read and process the web file, but don't print its contents.  This option is often used for large files of macro definitions, formats, or typedef statements that must be included at the beginning of even very short web files; it clutters things up to print such header files all the time.

Note that files included via `@i' do not respond to `-i' or `-i!'.

Command-line option `-i!':  Don't read @I include files.

If a web file is included via `@I', for example

-------------------------------------------------------------------------------
@I formats.hweb
-------------------------------------------------------------------------------

then the `-i!' option means to ignore such files completely.  This option is seldom useful; the `-i' option *Note -i:: is more often used.

Command-line option `-L':  Select global language.

To select a global language from the command line, say `-Ll', where l is one of {c,c++,n,n9,r,r9,x}.  *Note Languages::

Command-line option `-l':  Echo input line.

The option `-l[mmm[:nnn]]' echoes the input line constructed by the input driver between lines mmm and nnn.  Missing nnn means echo to the end of file.  Missing mmm means echo from the beginning.

This option is useful as a debugging tool.  It is often used to verify that the input driver is inserting semicolons correctly.  For Fortran--77, it is also useful to verify that comments are being processed correctly.

Command-line option `-m':  Define WEB macro.

The command-line construction

-------------------------------------------------------------------------------
-mA(x)=x
-------------------------------------------------------------------------------

defines the WEB macro A as though the definition

-------------------------------------------------------------------------------
@m A(x) x
-------------------------------------------------------------------------------

had appeared at the beginning of the web file.

Command-line option `-m4':  Understand m4 built-in commands.

This tells FWEAVE to properly format the reserved words of the m4 preprocessor.  The use of this preprocessor is not recommended; use FWEB's built-in preprocessor instead.

Command-line option `-m;':  Append pseudo-semicolons.

When `-m;' is in effect, the construction `@;' is appended automatically to all WEB macro definitions.

This option is not recommended.  Insert the `@;' by hand when necessary, as in

-------------------------------------------------------------------------------
@m SET(x,y) x=1; y=2@;
-------------------------------------------------------------------------------

Command-line option `-n':  Set global language to Fortran--77.

*Note Languages:: *Note Fortran::

Command-line option `-n9':  Set global language to Fortran--90.

*Note Languages:: *Note Fortran::

Command-line option `-n;':  Supply automatic semicolons (Fortran).

This is the default mode of operation in Fortran--77; the input driver automatically appends a semicolon to each logical line of source code. Since it's the default, you don't have to use it unless you wish to negate it.  *Note Negating options::

Command-line option `-nb':  Number ifs and dos (Fortran).

In the woven output, extra comments are added to help one correlate the block structure of the code.

Command-line option `-np':  Print semicolons (Fortran).

Although the Fortran input driver automatically terminates logical lines with semicolons so that the innards of FWEAVE can process them correctly, the semicolons are by default not printed.  To make them be printed, use the `-np' option.

Command-line option `-n\':  Free-form syntax continued by backslash.

In Fortran--90, this turns on free-form syntax and sets the continuation character to be the backslash.  For example,

-------------------------------------------------------------------------------

     -n9[-n\]
     @
     @a
     program main;
     x = \
      y;
     end;

-------------------------------------------------------------------------------

In the tangled output the backslash is converted into Fortran-90's standard continuation character, the ampersand.

Command-line option `-n&':  Free-form syntax continued by ampersand.

In Fortran--90, this turns on free-form syntax and sets the continuation character to be the backslash.  For example,

-------------------------------------------------------------------------------

     -n9[-n\]
     @
     @a
     program main;
     x = &
      y;
     end;

-------------------------------------------------------------------------------

Command-line option `-n/':  Recognize short comments (Fortran).

The standard FWEB notation for a short comment is `// ...'.  However, in Fortran the `//' denotes concatenation by default.  To make it denote a short comment, use the `-n/' option.  For concatenation, use `\/'.

Command-line option `-n!':  Make '!' denote short comment (Fortran).

Command-line option `-o':  Don't overload operators.

Command-line option `-q':  Don't translate Ratfor.

Command-line option `-P':  Select TeX processor.

Say `-PT' or `-PL' to inform FWEAVE that its output will be processed by TeX or LaTeX, respectively.  If you always use LaTeX, it's easiest to put `-PL' into the .fweb file.

Command-line option `-p':  Buffer up a style-file entry.

This option can be used in the .fweb file to record style-file entries that are common to all runs.  This command buffers up the entries.  They are effectively placed at the beginning of the local style file, which is read after the command line is processed. *Note Style::

Command-line option `-r':  Set global language to Ratfor--77.

*Note Languages:: *Note Ratfor::

Command-line option `-r9':  Set global language to Ratfor--90.

*Note Languages:: *Note Ratfor::

Command-line option `-rg':  Set goto parameters.

This obscure parameter is used for Ratfor (and really should be a style-file parameter).  Please see the manual.

Command-line option `-k':   Suppress comments about Ratfor translation.

By default, the Ratfor translator writes comments about what command it is translating.  The `-k' option suppresses those comments.  Arguments to this command allows one to suppress comments about only particular commands; please see the reference guide.

Command-line option `-K':   Write comments about Ratfor translation.

This is the negative of `-k'; it forces comments about particular Ratfor commands.

Command-line option `-r;':  Turn on auto-semi mode (Ratfor).

Please don't use this command.  Insert semicolons by hand in your Ratfor code.

Command-line option `-rb':  Number ifs and dos (Ratfor).

In the woven output, extra comments are added to help one correlate the block structure of the code.

Command-line option `-r/':  Recognize short comments (Ratfor).

The standard FWEB notation for a short comment is `// ...'.  However, in Ratfor the `//' denotes concatenation by default.  To make it denote a short comment, use the `-r/' option.  For concatenation, use `\/'.

Command-line option `-r!':  Make '!' denote short comment (Ratfor).

Command-line option `-s':  Print statistics.

`-s' prints statistics about memory usage at the end of the run.

`-sm' prints statistics about memory usage at the end of the run, just as does `-s'; it also prints information about dynamic memory allocations as they occur.  `-smnnn' displays allocations of nnn bytes or more; if nnn is missing, 10000 is assumed.

Command-line option `-t':  Truncate identifiers.

The truncation option enables one to use a wider character set for identifiers than the language compiler will accept.  The standard example is vanilla-flavored Fortran, which doesn't allow the underscore. If one says ``-tn6{_}'', underscores will be removed from all identifiers, then the result will be truncated to length 6.  If the truncation procedure results in non-unique identifiers, these are listed.

Command-line option `-u':  Undefine macro.

`-uA' undefines the WEB macro previously defined on the command line (or in .fweb) via `-m'.

CAUTION:  This command can also undefine built-in WEB functions such as _IF.  Don't do that, since built-ins can use other built-ins behind the scenes; undefining one can cause very strange behavior.

Command-line option `-v':  Make all comments verbatim.

By default, comments are not passed to the tangled output.  With `-v', all comments are included verbatim in the tangled output.

Command-line option `-W':  Flag-setting commands for FWEAVE.

This is a family of commands that set flags appropriate for FWEAVE. Commands such as -W[ and -Wf can be combined as -W[f.

Command-line option `-w':

The command `-w' means ``Don't print `\input fwebmac.sty' as the first line of the .tex output file.''  The command `-wfname' means ``Print \input fname' as the first line.''

Command-line option `-x':  Reduce cross-reference information.

Cross-reference information (for FWEAVE) includes the table of contents ('c'), the index ('i'), and the module list ('m').  The command `-x' eliminates all of that information.  The command `-xletters' eliminates the piece of information corresponding to each letter in the list.  For example, `-xim' eliminates the index and the module list.

Command-line option `-X':  Print selected cross-reference information.

This command is the opposite of `-x'.  *Note -x::

Command-line option `-y':  Allocate dynamic memory.

This command changes the default size for a dynamically allocated memory buffer.  The buffers are indicated by a one- or two-character abbreviation such as "op".  The command `-yop200' allocates 200 units for the "op" buffer.

To query the default allocations, just say `-y'.

Command-line option `-Z':  Display default style-file parameters.

The command `-Zabc' prints to the screen the default contents of the style-file parameters beginning with "abc".  Just `-Z' prints everything.

Command-line option `-z':  Change name of style file.

The command `-znew.sty' changes the default style-file name ``fweb.sty'' to ``new.sty''.  The command `-z' means ``Don't read any style file.''

Command-line option `-.':  Don't recognize dot constants.

If this command is used, the processors will not understand that constructions such as .LT. are operators in Fortran or Ratfor.  This command is useful if one is trying to modernize the source code to deal with symbols such as '<' instead of .LT.

Command-line option `-\':  Explicitly escape continued strings.

Command-line option `-(':  Continue parenthesized strings with backslashes.

Command-line option `-:':  Set starting automatic statement number.

Useful for Fortran and Ratfor.

Command-line option `->':  Redirect output.

This changes the name of the output file.  If no name is given, output is redirected to the terminal.

Command-line option `-=':  Redirect output.

Equivalent to `->'.

Command-line option `-#':  Turn off comments about line and module numbers.

By default, tangled output includes comments about the line and module numbers corresponding to the current piece of code.  To eliminate this clutter, say `-#'.

In some cases, bugs in tangled Fortran output can be eliminated by using `-#'.

Command-line option `-+':  Don't interpret compound assignment operators.

Ratfor attempts to translate the commands ++, +=, --, -=, *=, and /= into code that behaves as its C counterpart.  To turn that off, use `-+'.

Command-line option `-/':  Recognize short comments (Fortran & Ratfor).

If this command is not used, the '//' construction will be interpreted as concatenation.

A fast way of invoking this option is with the global language command, such as

@n/

Command-line option `-!':  Make '!' denote short comment (Fortran & Ratfor).

--- COMMENTING STYLES ---

FWEB allows a variety of commenting styles. The visible comments are in the font \cmntfont, which defaults to \tenrm.

Invisible comments:

     @z...@x --- If a source or include file begins with `@z', then all
                 material is skipped until and including a line beginning in
                 column 1 with `@x'.

     @%       --- All material until and including the next newline is
                 completely ignored.

For example,

-------------------------------------------------------------------------------

     @z
     Author:  J. A. Krommes
     @x
     @c @% This sets the global language to C.
     @* EXAMPLE.

-------------------------------------------------------------------------------

Visible comments:

/* ... */ --- Long comment (may extend over several lines).

// ...    --- Short comment (terminated by next newline).

@(...@) --- Meta-comment.

     @n
     @a
             program main
     /* Get input. */
             call get_input // Read the parameter file.
     /* Process information.  Comments like this
        can be split over several lines. */
     @(
     Meta-comments provide a poor-man's alignment feature
      i --- counter
      x --- data value
     @)
             i = 1
             x = 2.0
             call exec(i,x)
             end

-------------------------------------------------------------------------------

--- MACROS and PREPROCESSING ---

Outer macros are defined by `@d'.  They are simply copied to the beginning of the output file.  This is most useful for C or C++ codes; it's a shorthand way of typing #define when the positioning of the #define is unimportant.

WEB macros with a variable number of arguments are indicated by an ellipsis, as in

-------------------------------------------------------------------------------
@m VAR(x,y,z,...) text
-------------------------------------------------------------------------------

Adjacent strings in macro text are automatically concatenated.

     ANSI C-compatible tokens:
      ##
      #parameter  --- Convert parameter to string (without expansion).

     Extensions to ANSI C macro syntax:
      #*parameter --- Like #parameter, but pass a quoted string through unchanged.
      #!parameter --- Don't expand argument.
      #'parameter --- Convert parameter to a single-quoted string (no expansion).
      #"parameter --- Convert parameter to a double-quoted string (no expansion).
      #0          --- Number of variable arguments.
      #n          --- n-th variable argument, counting from 1.
      #.          --- Comma-separated list of all variable arguments.
      #:0         --- Unique statement number (expanded in phase 1).
      #:nnn       --- Unique statement number for each invocation of this
                      macro (Expanded in phase 2).
      #<          --- Begin a section (module) name.
      #,          --- Internal comma; doesn't delimit macro argument.

Built-in functions are essentially macros, but they sometimes implement functions that a user could not define.  They all begin with an underscore and are in upper case.

Detailed discussion of these macros isn't here yet.  Please see guide.tex.

Built-in function _A:  Convert to ASCII.

Built-in function _ABS:  Absolute value.

Built-in function _ASSERT:  Assert a condition.

Built-in function _COMMENT:  Generate a comment.

Built-in function _DATE:  Today's date.

Built-in function _DAY:  The day.

Built-in function _DECR:  Decrement a macro.

Built-in function _DEFINE:  Deferred macro definition.

Built-in function _DO:  Macro do loop.

Built-in function _DUMPDEF:  Dump a macro definition to the terminal.

Built-in function _ERROR:  Send error message to output.

Built-in function _EVAL:  Evaluate an expression.

Built-in function _GETENV:  Get value of environment variable.

Built-in function _HOME:  The user's home directory.

Built-in function _IF:  Two-way conditional.

Built-in function _IFCASE:  n-way conditional.

Built-in function _IFDEF:  Two-way conditional.

Built-in function _IFNDEF:  Two-way conditional.

Built-in function _IFELSE:  Two-way conditional.

Built-in function _INCR:  Increment a macro.

Built-in function _INPUT_LINE:  Line number that begins current section.

Built-in function _L:  Change to lower case.

Built-in function _LANGUAGE:  Identifier for current language.

Built-in function _LANGUAGE_NUM:  Number of current language.

Built-in function _LEN:  Length of string.

Built-in function _M:  Define a macro.

Built-in function _MAX:  Maximum.

Built-in function _MIN:  Minimum.

Built-in function _MODULE_NAME:  Name of present WEB module.

Built-in function _MODULES:  Total number of independent modules.

Built-in function _OUTPUT_LINE:  Current line number of tangled output.

Built-in function _P:  The C preprocessor symbol '#'.

Built-in function _POW:  Exponentiation.

Built-in function _ROUTINE:  Current function (Ratfor only).

Built-in function _SECTION_NUM:  Number of current WEB section.

Built-in function _SECTIONS:  Maximum section number.

Built-in function _STRING:  Expand, then stringize.

Built-in function _STUB:

Built-in function _TIME:  The time.

Built-in function _TRANSLIT:  Transliteration.

Built-in function _U:  Change to upper case.

Built-in function _UNDEF:  Undefine a macro.

Built-in function _UNQUOTE:  Remove quotes from string.

Built-in function _VERBATIM:  (Obsolete)

Built-in function _VERSION:  Present FWEB version number.

--- LANGUAGES ---

A language command should appear somewhere in limbo, before the start of the first module.  That command sets the global language.

Language commands may be used within sections, but the new language remains in force only for that section.

Special remarks.  (Please see the manual.)

Special remarks.  (Please see the manual.)

Special remarks.  (Please see the manual.)

Special remarks.  (Please see the manual.)

Special remarks.  (Please see the manual.)

FWEB preprocessor commands may appear in either the definition or the code parts.  But BEWARE:  No matter where they appear, they are expanded during INPUT, not output.  (This is probably a design flaw.)

     @#define identifier --- Define a WEB macro; equivalent to `@m'.
     @#undef identifier  --- Undefine a WEB macro.

     @#ifdef identifier  --- Is WEB macro defined?  Equivalent to
                              `@#if defined identifier'.
     @#ifndef identifier --- Is WEB macro not defined?  Equivalent to
                              `@#if !defined identifier'.

     @#if expression
     @#elif expression
     @#else
     @#endif

--- RATFOR ---

     Ratfor--77 commands:
      break;
      case i:
      default:
      do ...; {...}
      else {...}
      for(a;b;c) {...}
      if(condition) {...}
      next;
      repeat {...} until(condition);
      return expression;
      switch(expression) {...}
      while(condition) {...}

     Additional Ratfor--90 commands:
      contains:
      interface name {...}
      interface operator(op) {...}
      interface assignment(assgnmnt) {...}
      module name {...}
      private:
      sequence:
      type name {...}
      where(expression) {...}

Caviats about Ratfor:  (Please see the manual.)

--- FORMATTING ---

This discussion isn't finished.  Please see the manual.

Pseudo-operators behave like a particular part of speech for the purposes of FWEAVE's formatting, but are invisible on output.  The pseudo-operators are

     @e --- pseudo-expression.  *Note @e::
     @; --- pseudo-semicolon.  *Note @;::
     @: --- pseudo-colon.  *Note @colon::

Several of the command-line options can be used to elicit information about the initial state of FWEB.

     -D --- Display information about reserved words.  *Note -D_::
     -y --- Display default dynamic memory allocations.  *Note -y::
     -Z --- Display default values of style-file parameters.  *Note -Z_::

--- CUSTOMIZATION ---

The default behavior of FWEB can be changed in a variety of ways.

     (1) Unix environment variables (logical variables in VMS) affect path or
         file names.
     (2) An initialization file resides in the home directory.
     (3) A style file resides in the current directory.

* The initialization file (usually called .fweb) is intended to contain command-line options that are to be used in every run.

* The style file is intended to provide more local customization, perhaps differing for each run.

However, the `-p' option *Note -p:: provides a means of incorporating style-file entries into .fweb.

The order of processing is:

     (1) Evaluate environment variables.
     (2) Read .fweb.
     (3) Process .fweb options beginning with '+'.
     (4) Read and process command-line options (except for `-p').
     (5) Process remaining .fweb options.
     (6) Process any `-p' options.
     (7) Read and process the style file.

FWEB_INCLUDES --- Colon-delimited list of directories to search for include files.  (One can append to this list by means of the -I option.)

FWEB_INI --- Name of the initialization file. If not defined, either .fweb or fweb.ini is chosen, depending on the machine.  The initialization file always resides in $HOME.

FWEB_STYLE_DIR --- Directory in which style file resides.  If not defined, the current directory is used.

On startup, FWEB attempts to read an initialization file.  This always resides in the user's HOME directory.  It is usually called .fweb (fweb.ini) on personal computers.  The default file name can be overridden by the environment variable FWEB_INI.

One may put into .fweb any option that might be used as a command-line option.  (Presently, there must be just one entry per line.)  If the option begins with a '+', it is processed before the actual command-line options; otherwise, it is processed after.  Generally, .fweb options should begin with '+' so that one may override them from the command line.

The command-line option '-y' *Note -y:: is used to change the default allocation for a dynamic array.  The arrays have a one- or two-character abbreviation denoted by aa.  To query the present allocations of variable aa, just say `-yaa'.  To query everything, say `-y'.

The menu isn't here yet.  Please see Appendix N of the manual or reference guide.

A style file (default name fweb.sty) may reside in the user's current directory (or directory specified by the environment variable FWEB_STYLE_DIR).  The default name can be changed by the command-line option `-z'.

The style file is processed after all command-line options have been

processed.  Note that the command-line option `-p' *Note -p:: buffers up style-file entries.  Effectively, these are treated as residing in a temporary file that is read just before the local style file.  Thus, `-p' options placed in .fweb behave as `global' style-file entries and will be overridden by a matching entry in the local style file.

Style-file entries have the form

keyword [=] value

For example,

LaTeX.options = "eqalign"

The syntax is completely free-form.

Style-file parameters for customizing FWEAVE's index:

      index.tex      (string)
      index.preamble (string)
      index.postamble (string)
      index.collate  (string)
      group_skip     (string)
      lethead.prefix (string)
      lethead.suffix (string)
      lethead.flag   (integer)
      item_0         (string)
      delim_0        (string)
      delim_n        (string)
      underline.prefix (string)
      underline.suffix (string)
      language.prefix (string)
      language.suffix (string)

Style-file parameters for automatic file name completion:

      ext.web        (string) Extensions for the web file.
      ext.change     (string) Extensions for the change file.
      ext.hweb       (string) Extensions for include files.
      ext.hchange    (string) Extensions for change files associated with
                              include files.